package org.sibframework.sda.manager;

import java.io.Serializable;
import java.sql.SQLException;
import java.util.List;
import java.util.Map;

import org.sibframework.sda.SimpleDataAccess;

public interface IModelManager<E> {
	
	
	/**
	 * List all recode in table
	 * 列出该对象的所有数据。
	 * @return List of the object E.
	 */
	public List<E> list();
	
	/**
	 * Search in the table with all not null properties.
	 *  搜索一个对象，根据对象内非空的值来查找类似的对象。
	 * @param example search condition. all not null properties will became a where sentence
	 * @return List of the object E
	 */
	public List<E> search(E example);
	
	/**
	 * Search in the table with all not null properties and return the first object.
	 *  搜索一个对象并返回结果集中的第一个对象，根据参数对象内非空的值来查找类似的对象。s
	 * @param example
	 * @return First object E of that query
	 */
	public E searchFirst(E example);
	
	/**Search in the table with all not null properties.
	 * 搜索一个对象，根据第一个参数对象内非空的值来查找类似的对象，并根据第二个参数对象内的非空值来模糊过滤。
	 * @param example parameter for search
	 * @param like parameter for like search.
	 * @return List of the object E
	 */
	public List<E> search(E example, E like);
	
	/**
	 * execute a query SQL.
	 * 根据给定的blank sql来查询数据库，并返回对象结果集，查询到的数据库记录的内容会注入到对象实例的属性中
	 * @param sql to query
	 * @return List of the object E
	 */
	public List<E> query(String sql);
	
	/**
	 * execute a query SQL, with prepareStatement and array of value to set as "?".
	 * 根据给定的预编译的 sql和给定的?的值, 来查询数据库，并返回对象结果集，查询到的数据库记录的内容会注入到对象实例的属性中.
	 * @param sql SQL to prepareStatement
	 * @param params to set as "?"
	 * @return list of the object E.
	 */
	public List<E> query(String sql, Object[] params);
	
	/**
	 * get a recode by primary key.
	 * 根据主键查找
	 * @param id primary key
	 * @return object
	 */
	public E getById(Serializable id);
	
	/**
	 * get a recode by primary key
	 * 根据主键查找，主键值放在对象的对应属性中
	 * @param object object with the given primary key values
	 * @return object
	 */
	public E getById(E object);
	
	/**
	 * get a recode by code.
	 * 根据指定的code属性和code的值查找唯一的对象，
	 * @param codeName code column name.
	 * @param code code value.
	 * @return object
	 */
	public E getByCode(String codeName, Serializable code);

	
	/**
	 * search recodes by Non-unique code.
	 * 根据指定的code属性和code的值查找唯一的对象，
	 * @param codeName code column name.
	 * @param code code value.
	 * @return object
	 */
	public List<E> searchByCode(String codeName, Serializable code);
	
	
	/**
	 * update a object
	 * 更新一个对象
	 * @param object object to update, every properties will be set when update.
	 * @return recode count that has been afford.
	 * @throws Exception
	 */
	public int update(E object) throws SQLException ;
	
	
	/**
	 * update a object
	 * 更新一组对象
	 * @param objects objects to update, every properties will be set when update.
	 * @return recode count that has been afford.
	 * @throws Exception
	 */
	public int update(E[] objects) throws SQLException ;
	
	/**
	 * update a object only the give properties.
	 * 更新一个对象的某些字段。
	 * @param values give properties and names to update.
	 * @return recode count that has been afford.
	 * @throws Exception
	 */
	public int updateFields(Map<String, Object> values) throws SQLException ;
	
	/**
	 * insert a new recode into table
	 * 插入一个对象，
	 * @param object object to insert
	 * @return  recode count that has been afford.
	 * @throws Exception
	 */
	public int insert(E object) throws SQLException ;
	
	
	/**
	 * insert a new recode into table
	 * 插入一个对象，
	 * @param objects objects to insert
	 * @return  recode count that has been afford.
	 * @throws Exception
	 */
	public int insert(E[] objects) throws SQLException ;
	
	
	
	/**
	 * remove a recode from table.
	 * 删除一个对象，从传入对象取得主键值进行删除。
	 * @param object object to remove, 
	 * @return  recode count that has been afford.
	 * @throws Exception
	 */
	public int remove(E object) throws SQLException ;
	

	/**
	 * remove a recode from table.
	 * 删除一个对象，从传入对象取得主键值进行删除。
	 * @param objects objects to remove, 
	 * @return  recode count that has been afford.
	 * @throws Exception
	 */
	public int remove(E[] objects) throws SQLException ;
	
	
	/**
	 * remove a recode from table.
	 * 根据给数的主键值，删除一个对象，
	 * @param id primary key value to delete
	 * @return count of record removed
	 * @throws Exception
	 */
	public int remove(Serializable id) throws SQLException;
	
	
	/**
	 * get the model name.
	 * 获得当前Model Manager的对象的名字。
	 * @return model name
	 */
	public String getModelName();
	
	/**
	 * 创建一个Model对象的实力
	 * @return new model instance
	 */
	public E createModel();
	

	/**
	 * set the SimpleDataAccess object for transaction
	 * 设置SDA属性，用来控制事物。
	 * @param sda
	 */
	public void setSDA(SimpleDataAccess sda);

	/**
	 * get the SimpleDataAccess object
	 * 得到当前使用的sda
	 * @return return the using sda.
	 */
	public SimpleDataAccess getSDA();
	
	
	
	/**
	 * Close SDA.
	 */
	public void close();

}
